home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / x2ftp / msdos / libs / psy_kit / player.doc < prev    next >
Text File  |  1993-09-04  |  19KB  |  516 lines
  1. ███████████████████████████████████████████████████████████████████████████████
  2. ███████████████████████████████████████████████████████████████████████████████
  3. ███████████████████████████████████████████████████████████████████████████████
  4. ███████████████████████████████████████████████████████████████████████████████
  5. ████████████████████                                     ██████████████████████
  6. ████████████████████   Psychose'Player : DOCUMENTATION   ██████████████████████
  7. ████████████████████   ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀   ██████████████████████
  8. ████████████████████        Psychose'Player was          ██████████████████████
  9. ████████████████████    Coded by LCA of Psychose Inc.    ██████████████████████
  10. ████████████████████                V.1                  ██████████████████████
  11. ████████████████████                                     ██████████████████████
  12. ████████████████████     (C)opyright 1993 by LCA of      ██████████████████████
  13. ████████████████████            Psychose Inc.            ██████████████████████
  14. ████████████████████                                     ██████████████████████
  15. ███████████████████████████████████████████████████████████████████████████████
  16. ███████████████████████████████████████████████████████████████████████████████
  17. ███████████████████████████████████████████████████████████████████████████████
  18. ███████████████████████████████████████████████████████████████████████████████
  19. ███████████████████████████████████████████████████████████████████████████████
  20. ███████████████████████████████████████████████████████████████████████████████
  21. ███████████████████████████████████████████████████████████████████████████████
  22. █                                                                             █
  23. █                                                                             █
  24. █ 1) Introduction                                                             █
  25. █       α/ Who's done it?                                                     █
  26. █       α/ What for?                                                          █
  27. █       α/ Can you use it?                                                    █
  28. █                                                                             █
  29. █ 2) How to use it?                                                           █
  30. █       α/ What can it do?                                                    █
  31. █       α/ What can't it do?                                                  █
  32. █       α/ The Object-File : "PLAYER.OBJ"                                     █
  33. █                                                                             █
  34. █ 3) Do you want to contact "Psychose Inc."?                                  █
  35. █       α/ Use your MINITEL if you're French                                  █
  36. █       α/ Write to me                                                        █
  37. █                                                                             █
  38. █ 4) Conclusion                                                               █
  39. █                                                                             █
  40. █                                                                             █
  41. ███████████████████████████████████████████████████████████████████████████████
  42. ███████████████████████████████████████████████████████████████████████████████
  43. ███████████████████████████████████████████████████████████████████████████████
  44. ███████████████████████████████████████████████████████████████████████████████
  45. ███████████████████████████████████████████████████████████████████████████████
  46.  
  47.  
  48. 1) Introduction
  49. ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  50.     α/ Who's done it?
  51.     ═════════════════
  52.         I (LCA of "Psychose Inc.") coded this Object-File. It was of 
  53. course programmed in assembler.
  54.  
  55.  
  56.     α/ What for?
  57.     ════════════
  58.         This Object-File can play Amiga-Modules (.MOD files) on your
  59. Sound-Blaster (Pro) card. It can also play 6 or 8 channels Modules. Those
  60. Modules should be made, by example, on Fast-Tracker (Hei!! Mr.H/Triton, please
  61. insert in your coming version of Fast-Tracker a "Sample" option!!).
  62.         This Player requires 32bMM from Psychose Inc., because the
  63. module is played in XMS-Memory. Therefore, you've got lots of free conventional
  64. memory!!
  65.         Of course this player requires a 80386 or above processor.
  66.  
  67.  
  68.     α/ Can you use it?
  69.     ══════════════════
  70.         This Object-File is FreeWare : you can use it IF AND ONLY IF :
  71.             * The program using Psychose'Player is not a commercial
  72. program (shareware is considered as commercial software).
  73.             * You mention in your program that you used
  74. "Psychose'Player".
  75.             * Psychose'Player is not modified in any way and stay
  76. in its original form.
  77.  
  78.         You can (sorry, YOU MUST!!!!) copy the Psychose'Player package.
  79. I just hope it won't be used by little coders also called lamers............
  80.  
  81.         Moreover, SEND me your programs using Psychose'Player, I would
  82. be pleased to try them!!!
  83.  
  84.  
  85.  
  86. ████████████████████████████████████████████████████████████████████████████████
  87.  
  88. 2) How to use it?
  89. ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  90.     α/ What can it do?
  91.     ══════════════════
  92.     * It detects if a Sound-Blaster/Sound-Blaster Pro card is installed.
  93. It also detects the I/O Port and the IRQ. But the DMA channel must be 1.
  94.     * If a Sound-Blaster Pro card was detected, then the modules will be
  95. played in Stereo.
  96.     * The modules are converted into a Fast-Format in memory.
  97.     * If an XMS-Driver was detected by 32bMM, then this Fast-Format module
  98. will be located in XMS-Memory.
  99.     * It uses the Flat-Real Mode
  100.     * It can load old-15-Instr. modules
  101.     * It can play 4 or 6 or 8 channels modules
  102.         It detects the number of voices with the "M.K." bytes:
  103. in 6/8 channels Modules, those bytes are changed by the tracker in "6..." or
  104. "...6" (for a 6 channels module) where "..." can be anything.
  105.     * Using DMA for a faster Replay-Routine
  106.         * 4 playing-modes which 3 are very useful!!
  107.         - 50 Hz Mode (useless mode!!) : You must call a procedure at
  108. least 50 times per second.
  109.         - "Auto-Mode" (useful mode!!) : You've got NOTHING to do.
  110.                 - "Calling-Mode No1" (useful mode!!) : You set the frequence
  111. (=f) at which you'll call a Procedure (f>50 Hz). With this mode, you can make
  112. some nice effects on screen such as rasters, without a problem because
  113. interrupts are disabled.
  114.                 - "Calling-Mode No2" (useful mode!!) : It is exactly the same
  115. mode as the one above EXCEPT that now interrupts are enabled and the quality is
  116. much better!!
  117.      Don't worry, I'll soon explain you how to use those modes...
  118.  
  119.  
  120.     α/ What can't it do?
  121.     ════════════════════
  122.     * Arg!! It doesn't support all Effects, only the most important. It
  123. supports:
  124.         - 0xy : Normal Play/Arpeggio
  125.         - 1xx : Slide Up
  126.         - 2xx : Slide Down
  127.         - Axy : Volume Slide
  128.         - Bxx : Position Jump
  129.         - Cxx : Set Volume
  130.         - Dxx : Break Pattern
  131.         - Fxx : Set Tempo
  132.     As soon as I can, I'll code other effects...
  133.     * It can't detect the DMA channel.
  134.  
  135.  
  136.     α/ The Object-File "PLAYER.OBJ"
  137.     ═══════════════════════════════
  138.         To use Psychose'Player in your programs, you just have to do two
  139. things:
  140.     * Insert the line:
  141. INCLUDE PLAYER.INC
  142. INCLUDE 32bMM .INC
  143.                in your source-text.
  144.     * LINK your Objects-Files with "PLAYER.OBJ" and "32bMM.OBJ".
  145.  
  146. Note : The Psychose'Player Procedures or Variables are in a FAR-Segment, but the
  147. Class of this segment is 'CODE' so that you won't have problems to set the
  148. memory size needed by your program, as you'll soon see in the example-file.
  149.  
  150.  
  151.         Ok, here you'll learn how to call the Psychose'Player Procedures
  152. with their parameters and so on.....
  153. (See the Example-File for a concrete use)
  154.  
  155. 1) VARIABLES
  156.         * Num_Voices (Byte)
  157.     Here you'll have the number of channels there are in the current
  158. Module.
  159.  
  160.         * Max_Volume (Byte)
  161.     This is the higher Volume with which an instrument can be played. You
  162. can make a fade Up/Down with this variable.
  163.  
  164.         * Pattern_Index (Byte)
  165.     This is the number corresponding to the pattern being played. With this
  166. variable, you can synchronize your program with the music.
  167.  
  168.         * Beat_Index (Byte)
  169.     This is the line in current pattern. With this variable, you can
  170. synchronize your program with the music.
  171.  
  172.         * Voice_Info (Structure)
  173.     For each channel, there are in this structure the needed informations
  174. concerning the sound to play. This structure is useful for you for one reason:
  175. the byte "VmVolume". Indeed, this is the Volume of the Channel. You can do
  176. whatever you want with this byte. At every new note, the Volume is put in this
  177. byte. Here is the way to make a Vue-Meter:
  178. Vue_Meter:
  179.         mov ax,Seg Num_Voices
  180.         mov fs,ax
  181.         mov cl,fs:Num_Voices        ; number of voices
  182.         mov esi,fs:PTR_Voice_Info    ; 32 bits pointer (see below)
  183. Label_0:    mov al,[gs:esi].VmVolume    ; keep vue-meter value
  184.         dec [gs:esi].VmVolume        ; self-decrementing volume
  185.         call Draw_VueMeter        ; whatever you want!!
  186.         add esi,Size Struc_Voice_Info
  187.         dec cl
  188.         jne Label_0
  189.  
  190.  
  191.     Here is the total structure, but lots of bytes are USELESS for you!!
  192. Struc_Voice_Info    STRUC
  193.   Off_InstrInfo        dd ?
  194.   OffsetDigit        dd ?
  195.   Instrument        db ?
  196.   InstrVolume        db ?
  197.   VmVolume        db ?
  198.   InstrFineTune        db ?
  199.   Arp_Counter        db ?
  200.   QueDalle        db ?
  201.   Rate            dw ?
  202.   Corrector        dd ?
  203.   CorrectorVal        dd ?
  204.   EffectCommand        dw ?
  205.   SauveRate        dw ?
  206. Struc_Voice_Info    ENDS
  207.  
  208.         * PTR_Voice_Info
  209.     This is a 32 bits pointer of Voice_Info. This is useful in Flat-Real
  210. mode. See the example above...
  211.  
  212.  
  213. 2) PROCEDURES
  214.         * InitPlayer
  215.     -Parameters:
  216.         CALL    : AX = Playing-Rate (Maximum is 22000 Hz)
  217.         RETURN    : Nothing
  218.  
  219.     -Action:
  220.     You must call this procedure at the beginning of your program. It
  221. detects if a Sound-Blaster (Pro) card is installed, its I/O Port and its IRQ.
  222. It also saves the Interrupt Controler (8259) status.
  223.  
  224.  
  225.         * EndPlayer
  226.     -Parameters: Nothing
  227.  
  228.     -Action:
  229.     You must call this procedure at the end of your program. It restores
  230. the 8259 status.
  231.  
  232.  
  233.         * InfoSoundBlaster
  234.     -Parameters:
  235.         CALL    : Nothing
  236.         RETURN    : AL=Sound-Card (see the constants below)
  237.               AH=IRQ number
  238.               DX=I/O Port
  239.     -Action:
  240.     It returns the sound-config.
  241. In AL, there can be one of the following values:
  242. No_SB     = 0   : Sound-Blaster not detected
  243. SB_Mono   = 1    : Sound-Blaster detected
  244. SB_Stereo = 2    : Sound-Blaster Pro detected
  245.  
  246.  
  247.         * LoadModule
  248.     -Parameters:
  249.         CALL    : DS:DX : Offset of an ASCIIZ String corresponding to
  250. the name of the module to load (and of course to play!!)
  251.         RETURN    : Carry=0 : Ok : No error
  252.               Carry=1 : Arg!! ERROR!!!!
  253.     -Action:
  254.     This procedure loads a file and convert it into a new Fast-Format in
  255. XMS-Memory (if it can!!). If there is an error when loading, or if there is not
  256. enough free memory, then Carry=1.
  257.  
  258.  
  259.         * EraseModule
  260.     -Parameters: Nothing
  261.     -Action:
  262.     It erases the Module from the memory. You MUST call it before calling
  263. End-Player, or if you want to load another module:
  264. Example:
  265.         call Init32bMM            ; Init Flat-Real Mode
  266.         mov ax,18000            ; 18Khz
  267.         call InitPlayer
  268.         lea dx,NameModule_1
  269.         call LoadModule
  270.         call EraseModule
  271.         lea dx,NameModule_2
  272.         call LoadModule
  273.         call EraseModule
  274.         call EndPlayer
  275.         call End32bMM
  276.  
  277.  
  278.         * ConvertModule
  279.     -Parameters:
  280.         CALL    : GS:ESI = 32 bits offset of the module in memory
  281.               CX=Size in Kilo-Byte of the .MOD File.
  282.         RETURN    : Carry=0 : Ok
  283.               carry=1 : ERROR!! (Not Enough Memory!!)
  284.     -Action:
  285.     It converts the loaded Module (.MOD file) into the Fast-Format and it
  286. tries to put this new Format in XMS-Memory. Usualy, you don't need to call this
  287. procedure except if you've got your own file-loader.
  288.  
  289.  
  290.         * StartPlaying
  291.     -Parameters:
  292.         CALL    : AL=Playing-Mode
  293.                           If AL=Mode_2 or Mode_3, then BX=Calling Rate
  294.         RETURN    : Nothing
  295.     -Action:
  296.     Well I think it's not too difficult to understand what it does!!
  297. You put in AL the Playing-Mode. The correct values are:
  298. Mode_0    = 0
  299. Mode_1    = 1
  300. Mode_2    = 2
  301. Mode_3  = 3
  302.  
  303. I shall now explain you what those Playing-Modes are:
  304. ** Mode_0 :    In this mode, you MUST call a procedure at least 50 times a
  305. second. This Procedure is HandleMusic0 (see below). This Mode is totaly
  306. USELESS!!!
  307.     But why did I let it??
  308.     Well I let it because it emulates the Amiga Players (they are called
  309. 50 times a second). And, as you'll learn soon, the Mode 1 uses HandleMusic0,
  310. so I let this Procedure PUBLIC...
  311. Don't worry, it doesn't take a simple byte more in memory!!
  312.  
  313. ** Mode_1 :    This is the easier mode : you haven't got anything to do!!!
  314. Example:    call Init32bMM
  315.         mov ax,18000
  316.         call InitPlayer
  317.         lea dx,Name_Module
  318.         call LoadModule
  319.         mov al,Mode_1
  320.         call StartPlaying
  321.         ....            ; your program
  322.         ....
  323.         ....
  324.         call StopPlaying
  325.         call EraseModule
  326.         call EndPlayer
  327.         call End32bMM
  328.  
  329.     How does it work?
  330.     In this mode, as soon as the DMA-Buffer is totaly sent to the Sound-
  331. Blaster's DAC, the Sound-Blaster informs it to the CPU, with its IRQ channel.
  332. Then the IRQ handler fills a new DMA-buffer (it uses, of course, a double-
  333. buffering technik). That way, the IRQ-handler is called 50 times a second.
  334. Here is its algorithmus:
  335.         begin
  336.           Send new DMA-Buffer to the DAC
  337.           Call HandleMusic0 to prepare a buffer
  338.         end
  339.  
  340. ** Mode_2 : This is the calling mode.
  341. I think you'll understand how it works threw an example:
  342. Example:
  343.         call Init32bMM
  344.         mov ax,18000
  345.         call InitPlayer
  346.         lea dx,Name_Module
  347.         call LoadModule
  348.         mov al,Mode_2
  349.         mov bx,70        ; calling rate : 70 times a second
  350.                                         ; at regular steps
  351.         call StartPlaying
  352. Loop_0:        call Wait_VBL
  353.         call HandleMusic2    ; Call HandleMusic2 at each VBL
  354.                     ; that means, 70 times a second
  355.                     ; in 320*200 graphic mode.
  356.         in al,60h
  357.         cmp al,01h        ; ESC?
  358.         jne Loop_0
  359.         call StopPlaying
  360.         call EraseModule
  361.         call EndPlayer
  362.         call End32bMM
  363.  
  364.  
  365. Is it Ok??
  366. If you are in 320*240 graphic mode, then BX=60......
  367. Well maybe, you'll have little problems in stereo. This is VERY easy to
  368. understand why, and therefore, to solve them!!
  369. Before, I WANT to tell you THIS IS NOT A BUG!!!!!!!!!
  370.  
  371. If the sound goes right and left and right and...
  372. Why?
  373.     This is because of the DMA-buffer length calculation with the Sound-
  374. Blaster's DAC-Processor. With this bad length, a DMA-Session takes more than
  375. a period (in the upper example, a DMA session may take more than 1/70° second).
  376. And you call HandleMusic2 at every period <=> you cut a DMA-Session to put a
  377. new one, and in Stereo, the DAC doesn't like it!!
  378.     The error calculation depends on the Playing-Rate (18000Hz in the
  379. example) but it doesn't depend on the Calling-Rate (70Hz).
  380.     Have you already found the solution?? No??
  381.     Well, just put a higher Calling-Rate, so that the period will be
  382. smaller.
  383. Example:
  384.     If a Calling-Rate of 70Hz "bugs", then :
  385.         ...
  386.         ...
  387.         mov al,Mode_2
  388.         mov bx,71        ; a higher calling-rate
  389.         call StartPlaying
  390.         ...
  391.         ...
  392.  
  393. And don't worry, the music won't sound bad!!
  394. REMEMBER IT: NEVER call HandleMusic2 when the current DMA-Session isn't
  395. finished!!
  396.  
  397. ** Mode_3 : The concept of this mode is inspired from both mode_0 and mode_2.
  398. With StartPlaying, you put in AL the number 3 and in BX the frequency at which
  399. you will call the Calling_Procedure (=HandleMusic3)in a second. For instance,
  400. in you set a frequency of 65, then you MUST call at least HandleMusic3 65 times
  401. in a second. You can call it with irregular steps if you want...
  402. What is the difference between Mode_2 & Mode_3??
  403.   hehe!! the difference is in the DMA-management: in Mode_2, the DMA is
  404. programmed at which call, but in Mode_3, the DMA is programmed by an interrupt
  405. controller that is called by the Hardware (SB-IRQ). The second difference is
  406. that the Mode_3 fills a VERY VERY VERY... VERY big buffer (0.5 second!!),
  407. therefore, the quality of the tune is higher.
  408. You can call HandleMusic3 at irregular steps if you want, provided that you call
  409. this procedure BX times a second at least!!
  410. You should call HandleMusic3 more times than set with StartPlaying (=BX), so as
  411. to prevent from missing a Buffer-Filling. For example, if you want to call it
  412. 70 times a second, you should put in BX the value 68. (You've got 2 chances to
  413. miss the synchro!!).
  414.  
  415.  
  416.  
  417.         * StopPlaying
  418.     -Parameters: Nothing
  419.     -Action: Guess!!
  420.  
  421.  
  422.         * MusicMode
  423.     -Parameters:
  424.         CALL    : AL=Playing-Mode
  425.               If AL=Mode_2 then BX=Calling-Rate
  426.         RETURN    : Nothing
  427.     -Action : It changes (while a music is played) the current Playing-
  428. mode.
  429. Analyse the following example to use this Procedure in the good way:
  430.  
  431.         call Init32bMM
  432.         mov ax,18000
  433.         call InitPlayer
  434.         lea dx,Name_Module
  435.         call LoadModule
  436.         mov al,Mode_1
  437.         call StartPlaying    ; you are now in Mode_1
  438.  
  439.         mov cx,70*5        ; wait 5 seconds:
  440. Loop_0:        call WaitVBL
  441.         loop Loop_0
  442.  
  443.         mov al,Mode_2
  444.         mov bx,71
  445.         call MusicMode        ; You are now in Mode_2
  446.         hlt            ; Wait for the end of the DMA-session
  447.                     ; You can know when it finishes,
  448.                     ; because at the end of each one
  449.                     ; there is an interrupt.
  450.         mov cx,70*5
  451. Loop_1:        call WaitVBL        ; You may hear a little "TIC"
  452.         call HandleMusic2
  453.         loop Loop1
  454.         mov al,Mode_1
  455.         call MusicMode        ; You are now in Mode_1
  456.         mov ax,Seg Max_Volume
  457.         mov fs,ax
  458. Loop_2:        call WaitVBL        ; Fade down
  459.         call WaitVBL
  460.         dec fs:Max_Volume
  461.         jne Loop_2
  462.  
  463.         call StopPlaying
  464.         call EraseModule
  465.         call EndPlayer
  466.         call End32bMM
  467.  
  468.  
  469.         * HandleMusic0
  470.         * HandleMusic2
  471.     -CALL    : Nothing
  472.     -Action    : It fills a DMA-Buffer... See the procedures above for more
  473. informations.................
  474.  
  475.  
  476.  
  477. ████████████████████████████████████████████████████████████████████████████████
  478.  
  479. 3) Do you want to contact "Psychose Inc."?
  480. ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  481.  
  482.     If your deepest dream is to get in touch with us (hahaha!!!???), then
  483.  
  484.     α/ If you are French, use your lovely MINITEL:
  485.     ══════════════════════════════════════════════
  486.  
  487.     * 3615 RTEL
  488.         BAL : LCA        (Coder of Psychose Inc.)
  489.         BAL : NAPALM        (......................)
  490.         BAL : HACKER CROLL    (......................)
  491.  
  492.  
  493.     α/ If you wanna contact me, then write to:
  494.     ══════════════════════════════════════════
  495.  
  496.     BERMOND Cedric (LCA)
  497.     12, Rue Paul RONIN
  498.     42100 Saint-Etienne
  499.     FRANCE
  500.  
  501.     But, you must know that I may not answer to every letters since I am
  502. not rich and I've got lots of homework with my study.
  503. Therefore can you put in your letter a self-addressing envelope???
  504.  
  505.  
  506.  
  507. ████████████████████████████████████████████████████████████████████████████████
  508.  
  509. 3) Conclusion
  510. ▀▀▀▀▀▀▀▀▀▀▀▀▀
  511.  
  512.     I hope you'll enjoy this Object-File.
  513.     Well I haven't got anything else to tell you, so
  514. Have a good programming (ASM ONLY!!!!!!),
  515.         LCA of Psychose Inc.
  516.